=======================================================================
=     Illusion Softworks MAFIA 4DS fitler       for ZModeler v1.06    =
=                                                 (c) Oleg M. 2002    =
=======================================================================

Last Updated: 28.December.2002

==================================================
        CONTENTS
==================================================
        WHAT'S NEW
        GENERAL INFORMATION
        LEGAL
        FEATURES
        KNOWN BUGS
        REQUIRED TOOLS
        IMPORTING
        IN ZMODELER
        EXPORTING
        LOCKING FILES
        CONTACT INFORMATION

=========================
      WHAT'S NEW
=========================
- First release


=========================
   GENERAL INFORMATION
=========================

4DS.zmf is a filter (plug-in) for ZModeler v1.06f and higher. Filter
allows you to open (import) and save (export) Mafia .4DS files that
are compatible with the game.

Mafia wasn't intended to support user add-on cars, thus, you can only
replace stock cars.

ZModeler is not a Mafia editor!


=========================
         LEGAL
=========================
Replacing cars, modifying them or even extracting any files from .DTA
files is initially illegal. You are the only resposible for any
consequence it might cause.

Reusing (converting into other games, selling etc.) of any stock Mafia
models (meshes/art) is law-breaking. You have been warned,
BE RESPONSIBLE!

Converting any car into Mafia for farther release requires prior
agreement of the author.

All exported files are initally locked to prevent them from been
imported and/or converted.



=========================
        FEATURES
=========================
4DS filter provides you the following features:

Importing 4DS files
  + meshes (breaked into to sub-objects)
  + textures (should be previousely extracted from .DTA files into
    ../Maps folder. Textures are automatically converted into TGA
    format where required. For example, CLGL.BMP and CLGL+.BMP are
    converted to CLGL.TGA
  + materials properties: color, chrome and glowing features
    are supported.
  + two standard ZModeler's blending modes supported: No-blend and
    high-blend.
  + maintaining hierarchy local axes orientation, object's kinds and
    LOD information
  + collision information

Exporting scene in 4DS format
  + meshes (including LODs, axes orientation and hierarchy)
  + textures names convertion (all textures references are converted
    to .BMP files references where applied).
  + files locking
  + materials properties: color, chrome and glowing.
  + two standard ZModeler's blending modes are converted to materials
    with according settings
  + collision information
Objects settings toolbox (Tools\Filters\Mafia)
  + Viewing and setting object's type.

The following features are maintained by the game and remain available
for exported (modded or created meshes):
  + glowing headlight/taillight effects
  + turning signals
  + collision is generated from dummy objects
  + wheels (turning front/ non-turning rear)
  + turning steering wheel
  + crackable and smashable glasses
  + fall-off parts: bumpers ang lights
  + opening doors.
  + car's damaging/deforming

=========================
       KNOWN BUGS
=========================
  - LOD distances are hard-coded and might not fit properly.
  - scratches on the car's body might disappear.
  - some objects orientation problem (usually with AXIS00 and AXIS01)


=========================
     REQUIRED TOOLS
=========================
You need MafiaXTractor to unpack .DTA files and patch the rw_data.dll.
The patched rw_data.dll file can be downloaded from ZModeler's
homepage.


=========================
       IMPORTING
=========================
To import 4DS file, start ZModeler, hit Import button or press Ctrl-I
or goto file/import, pick the file and click 'Open' in a dialog box.
The importing might take some time, especially, if textures
convertion is required.

Locked 4DS files will not be imprted and an error box will appear.
YOU CAN'T IMPORT LOCKED FILES, SO YOU SHOULD HAVE YOU WORK SAVED AS
.Z3D FILE IN ORDER TO MODIFY IT FARTHER.

Imported mesh might appear off-screen, so you might need to scroll
views and navigate 3DView's camera.


=========================
      IN ZMODELER
=========================
Of cause, you either know ZModeler well or downloaded downloaded lots
of tutorials to learn it;). Anyway, the following information might be
helpfull in any case, since it's a valueable 4DS-specific information.

1. Objects Properties
First of all, the filter provides you a settings box in main menu:
Tools\Filters\Mafia\"Objects Settings". This toolbix allows you to
view and modify object's types. Note, EACH OBJECT MUST HAVE A TYPE SET
PROPERLY BEFORE EXPORTING. There are six types of objects:
a) Dummy - is the 'virtual' object that LS3D engine uses to recognise
   parts and their purpose. The dummy objects are not rendered by the
   engine as is (cubes), while their sub-objects (hierarchy children)
   might be rendered. For example, EXHAUST is used to place the smoke
   exhaust and turn smoke generation into right direction; DWHLx are
   the wheel dummies and their children are visual objects: wheels;
   BODYCOLBOx are body collision nodes and their sub-objects (several
   cubes) make the collision volume; CENTER is the simplest bounding
   box and so on.
b) Default - is a generic renderable object. It does not take damage.
c) Body - is deformable and scratchable part of the car. These are
   the body itself, doors, hood, trunk and so on they take damage but
   do not fall off.
d) Bumper - a part that bends and falls-off with the certian sound.
   You can have as many of these as you want and they dont have to be
   bumpers example: mirrors, wipers, etc.
e) Glass - a crackable and smashable part that, when damage, falls to
   small pieces with a known sound :)
f) Lamp/foglamp - a part that flash-off with a bit other sound:).
   Probably, used by the game for some other purpose too. (i think
   this is like a bumper mixed with headlight - so when it falls off
   the light no longer appears - these objects are optional).


2. Objects names
Objects names are generaly used for Dummy-type objects. Almost all
other objects can be named in any way (don't panic seen objects named
like 'vvvvvvv', 'dddd', 'sedddd', 'object01' and so on, as most object
names do not matter. For example. you could name the main body object
'this is not the body' and it would still show up in game).
Dummies object names are converted to uppercase. Other object's names
are used to distinct LODs info.

LODs (level of detail's) info is taken form the object name. LOD number
is written as a number after colomn. The following objects makes one
object 'body' with three LODs: 'body', 'body:1' and 'body:2'. The
order of objects in ZModeler's objects list is not significant, but
hierarchy relation of these nodes is preferable (all the lod objects
should be a children of one node).

In brief: body is what you would see close up, body:1 would appear
when you are a bit further away, then body:2.. etc, these are not
required but may improve game performance as it doesnt draw a 
high-poly object from far away that you cant really see anyway!


3. Hierarchy.
Hierarchy is maintained via Hierarchy browser and affects relation of
objects in-game. It's very important to maintain the game files guide
of hierarchy. I mean import any stock car and write down hierarchy
relations: it would be a nice guide. Wheels are under DWHL nodes,
Glasses are under according Door nodes, Doors are in 'BODY' and BODY
contains lots of other stuff.
   Thus, anything under doors node would move with the door, anything
under 'body' node moves with body, etc.


4. Polygons properties
Two ZModeler's standard properties have been mapped to .4DS materials
properties. They are No-Blend and High-Blend flags. All materials
should be made with chrome applied to them. To disable chroming, 'No-
Blend' polygons property should be applied. 'High-Blend' enables
higher chroming of polygons. Having niether 'high blend' or 'no blend' 
leaves a slight level of reflection suitable for car body etc.


4. Materials.
4.1. Color
Materials color affects the rendering in the game.

4.2. Alpha Chanell mode and texture names(!)
Alpha chanell mode (Alpha Parameters: "Type" box) is VERY IMPORTANT!
a) Unused:  The filter assumes that you use (if any) single BMP
            texture. Thus, if you have 'Unused' alpha type and a
            'car1.tga' texture loaded, then it will be exported as
            generic 'CAR1.BMP' texture reference.
b) Glowing: The filter will write a reference to a color-map texture
            and an alpha-chanel texture. If you have used 'car1.tga',
            then the color-map texture reference will be 'CAR1.BMP'
            and alpha-chanel reference will be 'CAR1+.BMP' (!!!!!)
c) Color Key: The filter will write a reference to a color-key
            texture. 'No smoothing' property will be set for according
            material. Texture MUST BE indexed-color BMP file and
            THE FIRST color in palette is the color-key (transparent).


4.3. Glowing mode
There is only one glowing modes that the filter recognises: 'Alpha
Glow with illumination effect'. This glowing kind generate a 'ONE'
blending of the 'destination' (in programming mode of material
editor). This glowing kind is exported as the 'glowing' object in the
game. This is NOT A GLOWING effect at the headlights/taillights, but
it surely might look almost the same.

4.4 Primary Texture apply mode
Among standard DISABLE ('no texture') and MODULATE ('Mix with color'),
the filter recognises ADD ('Light Map') mode and makes an according
material shining. This mode should be used on black materials when
creating a glowing headlight/taillight or other effects.


5. Objects local axes orientation.
It's recommended to apply Display\Local Axes\Reset tool to all the
objects, since the filter doesn't like axes orientation much. Axes
orientation is only important for animateable objects like wheels,
steering wheel, doors. And for some specific dummy objects like
exhaust. All other objects' axes can be easily reset to default. After
reseting, centering by obejct tool is worth applying.



=========================
       EXPORTING
=========================
4DS filter allows you to export .4DS files that are capatible with the
Mafia. You have to ensure in several things before you try to export
the scene.
  The following things have to be verified:
1) Objects types settings
2) Objects (especially Dummy-objects) names
3) Objects hierarchy
4) Materials

1. OBJECT TYPES
Open Mafia Objects Settings box and scroll the list of objects
verifying ALL objects kinds! There should not be mistake: If the
object is engine-control-node then it's a Dummy and it have a specific
name. Dummy object can have any names ONLY if it's a child of
BODYCOLBOx dummy. In this case the dummy is the part of collision
volume. If you are not sure what type you should set to a certain
object, set it to 'Default'.

2. OBJECT NAMES
Verify dummy objects names(!). Then, make sure you have properly named
LODs objects (if applied). Dummy object names are not case sensitive,
while all other objects are. Remember, first LOD object has no ":x"
addon and the second LOD has a ":1" addon. (obj, obj:1, obj:2).

3. OBJECTS HIERARCHY
Ensure that hierarchy is adjusted properly. I strongly recommend to
import any stock car, open a hierarchy browser and print it's content.

4. MATERIALS
Remember, the filter will convert any references to textures you have
used to .BMP references. This DOES NOT mean the filter will make these
BMP files. You will. But you have to be warned:).
Also, very important: avoid useless 'Glowing' materials: set them to
'Unused' where possible.
Missing textures is not a critical for Mafia. White untexture polygons
will appear if texture is missing.


=========================
     LOCKING FILES
=========================
The exported files are initially locked and the filter will not read
them if you try to import. In certain cases you might need to export
.4DS file without locking. This is allowed by the filter. To export
unlocked file, type it's name in export dialog box with UPPERCASE
extension. E.g. hit Export and type: mycar.4DS (instead of mycar.4ds)

=========================
   SOME USEFUL STUFF
=========================
Finding a 4ds file you want isn't easy, Mafia was made by a Czech
company and almost all 4ds files are named in czech!
I found this convertor very useful: http://www.slovnik.cz/bin/ecd

If you want to import, say, schubert for one thing the 4DS files have
REAL car name (ie ford or chevrolet), also you may find many files
relating to one car, here is a description:

chev00.4ds   -   What you see when u get IN the car
chev10.4ds   -   What you see driving around BEFORE you get in
                 (basicly same .4DS so dont know why this is)
chev01.4ds   -   Same as 00 but its a different color (colors chosen
                 in car select)
chev11.4ds   -   Same as 10 but its a different color (colors chosen
                 in car select)
chev02...
chev12... etc etc

Also cars have a 'blown up' version of them, the file name of this
changes, and some are shared between cars. Most are called
(Carname)_D.4ds or _E.4ds or something like this.


=========================
   CONTACT INFORMATION
=========================
URL: http://www.zmodeler.com
Comments, suggestions and feedback send to <funspeed@softhome.net>

This text file was written by Oleg M.
Visit http://www.mafia-game.com site and it's link section to find the
Mafia-related resources on the WEB.

Other questions concerned ZModeler can be asked on Zmodeler forum.
=======================================================================
                                Zanoza Modeler (c) Oleg M. 1999-2002

